docs(design): forge state-transition write op record (RIG-3331) - #981

Design record for the forge state-transition write op: an agent sets an
issue/PR state on both GitHub and Linear through the same attribution
chokepoint every other forge write rides.

Portable {open, closed} core plus per-provider refinements (close_reason on
GitHub, workflow_state on Linear), fail-loud invalid_argument on a
refinement/provider mismatch, ErrUnsupported on the Linear PR half.
Transitions mutate an existing coordinate, so they are neither F3-deduped nor
DL-055-recorded, following the comment-arm precedent.

The load-bearing contract is actor attribution: the emitted STATE event must
carry the acting agent so RIG-3326's suppression arm can key on the real
transition actor rather than the DL-055 author-row proxy, which would wrongly
eat a human-close notification to the author.

Two load-bearing Open Questions are held for Matt: the actor-carrier mechanism
(OQ-1, a cross-record contract with RIG-3326) and the Linear default
workflow-state rule (OQ-2, a product-behavior call).

Refs RIG-3331

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…d (RIG-3331)

Adversarial review returned 4 high, 5 medium, 3 low. Fixes, each verified
against the cited source:

Two fabricated citations removed (rule://planning-evidence). The record named
translateAttribution as an existing symbol - it does not exist anywhere in the
tree; the real path is stripBodyToRef plus the detect-path attribution
assignment. It also quoted 'deliberately never imports the store' as if from
the ingest package; the actual term of art is the no-store rule. Both
underlying claims were true, only the citations invented.

The F3/DL-055 argument reached the right conclusion from the wrong premise.
The comment arm is excluded because a comment is unrepresentable in the store
index; a transition targets a coordinate that IS representable and often
already occupied. The record inverted the risk as 'no row exists at the
coordinate at all'. The real hazard is a row that DOES exist:
RecordAuthoredArtifact's ON CONFLICT DO UPDATE overwrites client_request_id,
which backs the F3 memo through a unique partial index, so routing a
transition through record would destroy the original create's idempotency
memo. Conclusion kept, reasoning replaced, hazard named.

T1 was red by construction: it widened Provider while extending only the fake,
but four compile-time satisfaction assertions live in that package, so the
GitHub and Linear ones break immediately and T2/T3 (the repair) come after.
T1 now lands the interface with all four implementors.

The transition memo omitted tenant_id. Its sibling forge_authored_artifacts is
tenant-keyed and defended by a two-tenants-same-coordinate test, so without it
one tenant's memo could attribute another's STATE event. The RLS catalog test
audits tables that carry the column, so an omission is invisible to it - the
column now ships with three explicit obligations instead of a reliance on the
guard.

Three tasks silently depended on unruled Open Questions while the checklist
presented nine unconditional slices. T3 is OQ-2-contingent, T4's memo half and
all of T5 are OQ-1-contingent, each now tagged with what changes under the
alternative ruling.

Also: ruled the ambiguous-workflow-state-name case (Linear does not enforce
name uniqueness within a team) rather than leaving an implementer to invent a
rule on the write path; specified the workflow-state cache separately from the
invalidation-free teamIDs cache, since humans rename and reorder states;
named the webhook/sweep double-emission and cursor-advance races; stated the
memo read's tenant context; pinned the table to 0001_init.sql per the
collapsed-migration convention; corrected the DL enumeration to include PR
#932's DL-341; resolved the T8 contradiction (the rows ship in the freeze
push, because DL-343's substance is what OQ-1 asks Matt to rule, and stamping
'Active (Matt)' now would attribute a decision he has not made); and flipped
Status to Draft.

Refs RIG-3331

Co-authored-by: Matt Wilkinson <matt@rigel.build>

Both load-bearing Open Questions are ruled, so the record flips Draft ->
Active and its ledger rows land in this push.

- OQ-1: the actor carrier is the consumable `forge_state_transitions` memo,
  not a synthetic STATE event. RIG-3326 is the side whose text bends -- its
  STATE arm resolves the actor through a memo lookup rather than off the
  event body. T5 keeps its subject and T4's memo half is in scope.
- OQ-2: Linear default-state resolution defaults only where the target is
  unambiguous and fails `invalid_argument` naming the candidates otherwise,
  replacing the positional tie-break. A mandatory `workflow_state` was also
  rejected: it forces a provider-aware state fetch into every callsite and
  splits GitHub/Linear ergonomics. Measured at freeze, the Rigel team has
  exactly one `completed`, one `unstarted` and one `backlog` state, so the
  original "silently picks a board column" premise had no choice to make --
  the rejection arm is a guard against future drift, covered by fixture
  because no current board reproduces it.

All nine task slices are now unconditional; T3 gains the multi-candidate
rejection fixture. DL-342/DL-343 appended with the real ruling date, ids
re-verified next-free against main (highest DL-337) and every open design
PR (#913 338/339, #900 340, #932 341).

Refs RIG-3331

Co-authored-by: Matt Wilkinson <matt@rigel.build>